deps/SDL Full/docs/README-macosx.md

   1 Mac OS X
   2 ==============================================================================
   3
   4 These instructions are for people using Apple's Mac OS X (pronounced
   5 "ten").
   6
   7 From the developer's point of view, OS X is a sort of hybrid Mac and
   8 Unix system, and you have the option of using either traditional
   9 command line tools or Apple's IDE Xcode.
  10
  11 To build SDL using the command line, use the standard configure and make
  12 process:
  13
  14         ./configure
  15         make
  16         sudo make install
  17
  18 You can also build SDL as a Universal library (a single binary for both
  19 32-bit and 64-bit Intel architectures), on Mac OS X 10.7 and newer, by using
  20 the gcc-fat.sh script in build-scripts:
  21
  22     mkdir mybuild
  23     cd mybuild
  24     CC=$PWD/../build-scripts/gcc-fat.sh CXX=$PWD/../build-scripts/g++fat.sh ../configure
  25         make
  26         sudo make install
  27
  28 This script builds SDL with 10.5 ABI compatibility on i386 and 10.6
  29 ABI compatibility on x86_64 architectures.  For best compatibility you
  30 should compile your application the same way.
  31
  32 Please note that building SDL requires at least Xcode 4.6 and the 10.7 SDK
  33 (even if you target back to 10.5 systems). PowerPC support for Mac OS X has
  34 been officially dropped as of SDL 2.0.2.
  35
  36 To use the library once it's built, you essential have two possibilities:
  37 use the traditional autoconf/automake/make method, or use Xcode.
  38
  39 ==============================================================================
  40 Caveats for using SDL with Mac OS X
  41 ==============================================================================
  42
  43 Some things you have to be aware of when using SDL on Mac OS X:
  44
  45 - If you register your own NSApplicationDelegate (using [NSApp setDelegate:]),
  46   SDL will not register its own. This means that SDL will not terminate using
  47   SDL_Quit if it receives a termination request, it will terminate like a
  48   normal app, and it will not send a SDL_DROPFILE when you request to open a
  49   file with the app. To solve these issues, put the following code in your
  50   NSApplicationDelegate implementation:
  51
  52
  53     - (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
  54     {
  55         if (SDL_GetEventState(SDL_QUIT) == SDL_ENABLE) {
  56             SDL_Event event;
  57             event.type = SDL_QUIT;
  58             SDL_PushEvent(&event);
  59         }
  60
  61         return NSTerminateCancel;
  62     }
  63
  64     - (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
  65     {
  66         if (SDL_GetEventState(SDL_DROPFILE) == SDL_ENABLE) {
  67             SDL_Event event;
  68             event.type = SDL_DROPFILE;
  69             event.drop.file = SDL_strdup([filename UTF8String]);
  70             return (SDL_PushEvent(&event) > 0);
  71         }
  72
  73         return NO;
  74     }
  75
  76 ==============================================================================
  77 Using the Simple DirectMedia Layer with a traditional Makefile
  78 ==============================================================================
  79
  80 An existing autoconf/automake build system for your SDL app has good chances
  81 to work almost unchanged on OS X. However, to produce a "real" Mac OS X binary
  82 that you can distribute to users, you need to put the generated binary into a
  83 so called "bundle", which basically is a fancy folder with a name like
  84 "MyCoolGame.app".
  85
  86 To get this build automatically, add something like the following rule to
  87 your Makefile.am:
  88
  89 bundle_contents = APP_NAME.app/Contents
  90 APP_NAME_bundle: EXE_NAME
  91         mkdir -p $(bundle_contents)/MacOS
  92         mkdir -p $(bundle_contents)/Resources
  93         echo "APPL????" > $(bundle_contents)/PkgInfo
  94         $(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
  95
  96 You should replace EXE_NAME with the name of the executable. APP_NAME is what
  97 will be visible to the user in the Finder. Usually it will be the same
  98 as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME
  99 usually is "TestGame". You might also want to use @PACKAGE@ to use the package
 100 name as specified in your configure.in file.
 101
 102 If your project builds more than one application, you will have to do a bit
 103 more. For each of your target applications, you need a separate rule.
 104
 105 If you want the created bundles to be installed, you may want to add this
 106 rule to your Makefile.am:
 107
 108 install-exec-hook: APP_NAME_bundle
 109         rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
 110         mkdir -p $(DESTDIR)$(prefix)/Applications/
 111         cp -r $< /$(DESTDIR)$(prefix)Applications/
 112
 113 This rule takes the Bundle created by the rule from step 3 and installs them
 114 into $(DESTDIR)$(prefix)/Applications/.
 115
 116 Again, if you want to install multiple applications, you will have to augment
 117 the make rule accordingly.
 118
 119
 120 But beware! That is only part of the story! With the above, you end up with
 121 a bare bone .app bundle, which is double clickable from the Finder. But
 122 there are some more things you should do before shipping your product...
 123
 124 1) The bundle right now probably is dynamically linked against SDL. That
 125    means that when you copy it to another computer, *it will not run*,
 126    unless you also install SDL on that other computer. A good solution
 127    for this dilemma is to static link against SDL. On OS X, you can
 128    achieve that by linking against the libraries listed by
 129      sdl-config --static-libs
 130    instead of those listed by
 131      sdl-config --libs
 132    Depending on how exactly SDL is integrated into your build systems, the
 133    way to achieve that varies, so I won't describe it here in detail
 134 2) Add an 'Info.plist' to your application. That is a special XML file which
 135    contains some meta-information about your application (like some copyright
 136    information, the version of your app, the name of an optional icon file,
 137    and other things). Part of that information is displayed by the Finder
 138    when you click on the .app, or if you look at the "Get Info" window.
 139    More information about Info.plist files can be found on Apple's homepage.
 140
 141
 142 As a final remark, let me add that I use some of the techniques (and some
 143 variations of them) in Exult and ScummVM; both are available in source on
 144 the net, so feel free to take a peek at them for inspiration!
 145
 146
 147 ==============================================================================
 148 Using the Simple DirectMedia Layer with Xcode
 149 ==============================================================================
 150
 151 These instructions are for using Apple's Xcode IDE to build SDL applications.
 152
 153 - First steps
 154
 155 The first thing to do is to unpack the Xcode.tar.gz archive in the
 156 top level SDL directory (where the Xcode.tar.gz archive resides).
 157 Because Stuffit Expander will unpack the archive into a subdirectory,
 158 you should unpack the archive manually from the command line:
 159         cd [path_to_SDL_source]
 160         tar zxf Xcode.tar.gz
 161 This will create a new folder called Xcode, which you can browse
 162 normally from the Finder.
 163
 164 - Building the Framework
 165
 166 The SDL Library is packaged as a framework bundle, an organized
 167 relocatable folder hierarchy of executable code, interface headers,
 168 and additional resources. For practical purposes, you can think of a
 169 framework as a more user and system-friendly shared library, whose library
 170 file behaves more or less like a standard UNIX shared library.
 171
 172 To build the framework, simply open the framework project and build it.
 173 By default, the framework bundle "SDL.framework" is installed in
 174 /Library/Frameworks. Therefore, the testers and project stationary expect
 175 it to be located there. However, it will function the same in any of the
 176 following locations:
 177
 178     ~/Library/Frameworks
 179     /Local/Library/Frameworks
 180     /System/Library/Frameworks
 181
 182 - Build Options
 183     There are two "Build Styles" (See the "Targets" tab) for SDL.
 184     "Deployment" should be used if you aren't tweaking the SDL library.
 185     "Development" should be used to debug SDL apps or the library itself.
 186
 187 - Building the Testers
 188     Open the SDLTest project and build away!
 189
 190 - Using the Project Stationary
 191     Copy the stationary to the indicated folders to access it from
 192     the "New Project" and "Add target" menus. What could be easier?
 193
 194 - Setting up a new project by hand
 195     Some of you won't want to use the Stationary so I'll give some tips:
 196     * Create a new "Cocoa Application"
 197     * Add src/main/macosx/SDLMain.m , .h and .nib to your project
 198     * Remove "main.c" from your project
 199     * Remove "MainMenu.nib" from your project
 200     * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
 201     * Add "$(HOME)/Library/Frameworks" to the frameworks search path
 202     * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
 203     * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
 204     * Add your files
 205     * Clean and build
 206
 207 - Building from command line
 208     Use pbxbuild in the same directory as your .pbproj file
 209
 210 - Running your app
 211     You can send command line args to your app by either invoking it from
 212     the command line (in *.app/Contents/MacOS) or by entering them in the
 213     "Executables" panel of the target settings.
 214
 215 - Implementation Notes
 216     Some things that may be of interest about how it all works...
 217     * Working directory
 218         As defined in the SDL_main.m file, the working directory of your SDL app
 219         is by default set to its parent. You may wish to change this to better
 220         suit your needs.
 221     * You have a Cocoa App!
 222         Your SDL app is essentially a Cocoa application. When your app
 223         starts up and the libraries finish loading, a Cocoa procedure is called,
 224         which sets up the working directory and calls your main() method.
 225         You are free to modify your Cocoa app with generally no consequence
 226         to SDL. You cannot, however, easily change the SDL window itself.
 227         Functionality may be added in the future to help this.
 228
 229
 230 Known bugs are listed in the file "BUGS"